DataCombo Control

The DataCombo control is a data-bound combo box that is automatically populated from a field in an attached data source, and optionally updates a field in a related table of another data source.

Syntax

DataCombo

Remarks

The DataCombo control is code-compatible with the DBCombo control. However the DataCombo control is optimized to work with ActiveX Data Objects (ADO).

Distribution Note The DataCombo control is found along with the DataList control in the Msdatlst.ocx file. To use this control in your application, you must add the .OCX file to the project. When distributing your application, install the Msdatlst.ocx file in the user's Microsoft Windows System or System32 directory. For more information on how to add an ActiveX control to a Visual Basic project, see "Standard ActiveX Controls."


DataList Control

The DataList control is a data-bound list box that is automatically populated from a field in an attached data source, and optionally updates a field in a related table of another data source.

Syntax

DataList

Remarks

The DataList control is code-compatible with the DBList control. However the DataList control is optimized to work with ActiveX Data Objects (ADO).

Distribution Note This DataList control is found along with the DataCombo control in the Msdatlst.ocx file. To use this control in your application, you must add the .OCX file to the project. When distributing your application, install the Msdatlst.ocx file in the user's Microsoft Windows System or System32 directory. For more information on how to add an ActiveX control to a Visual Basic project, see "Standard ActiveX Controls."


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.


ReFill Method

Re-creates the list of a DataList or DBCombo control and forces a repaint.

Syntax

object.ReFill

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Remarks

The ReFill method is different than the standard Refresh method, which just forces a Repaint event.


DBCombo Control

The DBCombo control is a data bound combo box with a drop-down list box which is automatically populated from a field in an attached Data control, and optionally updates a field in a related table of another Data control. The text box portion of DBCombo can be used to edit the selected field.

Syntax

DBCombo

Remarks

The DBCombo control differs from the standard ComboBox control. While the ComboBox control list is filled using the AddItem method, the DBCombo control is automatically filled with data from a field in the Recordset object of a Data control to which it is attached. The standard ComboBox control must be populated manually by using the AddItem method. In addition, the DBCombo control has the ability to update a field within a related Recordset object which may reside in a different Data control.

The DBCombo control also supports an automated search mode that can quickly locate items in the list without additional code.

Shown below is a list of the properties used to fill and manage the DBCombo control, and bind the selected data to a Data control.

Property | Specifies
DataSource | Name of Data control that is updated once a selection is made.
DataField | Name of a field that is updated in the Recordset specified by the DataSource property.
RowSource | Name of Data control used as a source of items for the list portion of the control.
ListField | Name of a field in the Recordset specified by RowSource that is used to fill the drop-down list. DBCombo does not support fields of LongBinary type for the Listfield property.
BoundColumn | Name of a Field in the Recordset specified by RowSource to be passed back to the DataField once a selection is made. DBCombo does not support fields of LongBinary type for the BoundColumn.
BoundText | Text value of BoundColumn field. Once a selection is made, this value is passed back to update the Recordset object specified by the DataSource and DataField properties.
Text | Text value of the selected item in the list.
MatchEntry | How the list is searched as the user types in characters at run time.
SelectedItem | The bookmark of the selected item in the Recordset specified by the RowSource property.
VisibleCount | The number of items visible in the list (fully or partially).
VisibleItems | An array of bookmarks with a maximum number of items equal to the VisibleCount property.

Users can search the DBCombo control by typing a value into the text box portion of the control. Once entered, this value is located in the list and the current list item is set to that item. If the item is not found, the BoundText property is set to null.

Note If you do not make the boundary of the control large enough for at least one row of the dropdown list, the list will not appear at run time.


DBList Control

The DBList control is a data bound list box which is automatically populated from a field in an attached Data control, and optionally updates a field in a related table of another Data control.

Syntax

DBList

Remarks

The DBList control differs from the standard ListBox control. While the ListBox control list is filled using the AddItem method, the DBList control is automatically filled with data from a field in the Recordset object of a Data control to which it is attached. The standard ListBox control must be populated manually by using the AddItem method. In addition, the DBList control has the ability to update a field within a related Recordset object which may reside in a different Data control.

The DBList control also supports an automated search mode that can quickly locate items in the list without additional code.

Shown below is a list of the properties you use to fill and manage the list, and bind the selected data to a Data control.

Property | Specifies
DataSource | Name of Data control that is updated once a selection is made.
DataField | Name of a field that is updated in the Recordset specified by the DataSource property.
RowSource | Name of Data control used as a source of items for the list portion of the control.
ListField | Name of a field in the Recordset specified by RowSource that is used to fill the list. DBList does not support fields of LongBinary type for the ListField property.
BoundColumn | Name of a field in the Recordset specified by RowSource that is passed back to the DataField once a selection is made. DBList does not support fields of LongBinary type for the BoundColumn.
BoundText | Text value of the BoundColumn field. Once a selection is made, this value is passed back to update the Recordset object specified by the DataSource and DataField properties.
Text | Text value of the selected item in the list.
MatchEntry | How the list is searched as the user types characters at run time.
SelectedItem | The bookmark of the selected item in the Recordset specified by the RowSource property.
VisibleCount | The number of items visible in the list (fully or partially).
VisibleItems | An array of bookmarks with a maximum number of items equal to the VisibleCount property.

The DBList control will automatically highlight an item in the list if the BoundText property becomes equal to the value of the field specified by the DataSource and DataField properties, such as when using a Data control to change the current record.


BoundColumn Property

Returns or sets the name of the source field in a Recordset object that is used to supply a data value to another Recordset.

Syntax

object.BoundColumn [= value]

The BoundColumn property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A string expression that specifies the name of a field in the Recordset created by the Data control specified by the RowSource property.

Remarks

Generally, when working with the DataList and DataCombo controls, you use two Data controls; one to fill the list as designated by the Listfield and RowSource properties and one to update a field in a database specified by the DataSource and DataField properties.

The ListField property designates the field used to fill the list. The second Data control, as designated by the DataSource property, manages a Recordset containing a field to be updated. Once the user chooses one of the items in the list, the field specified by the BoundColumn property is passed to the field in the second Data control, as designated by the DataSource and DataField properties. This way you can designate one field to fill the list, and another field (from the same Recordset) to pass as data to the Recordset designated by the DataSource and DataField properties when an item is selected.

If the field specified by the BoundColumn property can't be found in the Recordset, a trappable error occurs.

Data Type

String


ListField Property

Returns or sets the name of the field in the Recordset object, specified by the RowSource property, used to fill the DataCombo or DataList control's list portion.

Syntax

object.ListField [= value]

The ListField property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A string expression that specifies the name of a field in the Recordset specified by the RowSource property.

Remarks

The ListField property enables you to select which field in the Recordset is used to fill the list portion of the control. This property is used in conjunction with the RowSource property that specifies which Data control is used to create the Recordset used to fill the list.

Generally, you use two Recordset objects with the data-aware list controls. One Recordset contains a read-only list of valid selections, while the other Recordset is updated with selections from the list. For example, the DataList control could be generated from a query that returned a list of valid part numbers and their descriptions. The ListField property would point to the description field of the Recordset, so that the user doesn't see the actual part numbers. The BoundColumn property would point to the part number field, as this is what needs to be updated in the Recordset.

If the field specified by the ListField property can't be found in the Recordset, a trappable error occurs.

Data Type

String


MatchedWithList Property

Returns True if the current content of the BoundText property matches one of the records in the list portion of the control.

Syntax

object.MatchedWithList

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Return Values

The MatchedWithList property return values are:

Value | Description
True | The content of the BoundText property matches one of the records in the list.
False | The contents of the BoundText property does not match any of the records in the list.

Remarks

When you enter a value in the text portion of the DataCombo control, the MatchedWithList property is set to True if the value entered is one of the items shown in the list. Moving the Data control specified by the DataSource property of the DataCombo or DataList control also sets the MatchedWithList property to True if the BoundText value matches one of the records in the list. In this case, the record is highlighted.

Data Type

Boolean


MatchEntry Property

Returns or sets a value indicating how the DataCombo or DataList control performs searches based on user input.

Syntax

object.MatchEntry [= value ]

The MatchEntry property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A constant or value that defines the behavior of a control when it has focus and the user enters one or more characters, as described in Settings.

Settings

The settings for value are:

Setting | Value | Description
dblBasicMatching | 0 | Basic Matching: (Default) The control searches for the next match for the character entered using the first letter of entries in the list. Repeatedly typing the same letter cycles through all of the entries in the list beginning with that letter.
dblExtendedMatching | 1 | Extended Matching: The control searches for an entry matching all characters entered. The search is done as characters are being typed, further refining the search.

Remarks

When the MatchEntry property is set to dblExtendedMatching and the user enters a backspace or waits more than a few seconds, the matching string is reset.

Data Type

Integer


RowSource Property

Sets a value that specifies the Data control from which the DataList and DataCombo controls' list is filled. Not available at run time.

Syntax

object.RowSource [ = value]

The RowSource property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A string expression that specifies the name of a Data control.

Remarks

To fill the list in a DataCombo or DataList control, you must specify a Data control in the RowSource property at design time using the Properties window.

To complete the connection with a field in the Recordset object managed by the Data control, you must also provide the name of a Field object in the ListField property.

Data Type

String


SelectedItem Property

Returns a value containing a bookmark for the selected record in a DataCombo or DataList control.

Syntax

object.SelectedItem

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Remarks

When you select an item in the list portion of the control, the SelectedItem property contains a bookmark that you can use to reposition to the selected record in the Recordset of the Data control specified by the RowSource property.

Data Type

Variant


VisibleCount Property

Returns a value indicating the number of visible items in the list portion of the DataCombo or DataList control.

Syntax

object.VisibleCount

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Remarks

The VisibleCount property returns an integer from 0 to the number of items visible in the control. An item is considered visible even if only a portion of the text is visible, as when the IntegralHeight property setting is False.

Note VisibleCount may be set to 0 before the first time the list portion of the DataCombo control is displayed.

Data Type

Integer


VisibleItems Property

Returns an array of bookmarks, one for each visible item in the DataCombo or DataList control's list.

Syntax

object.VisibleItems(Index)

The VisibleItems property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
Index | An Integer expression that specifies the element in the array. This value can be 0 to VisibleCount - 1.

Remarks

These bookmarks may be used to fetch individual records from the recordset used to fill the list.

Data Type

Variant


DataList and DBCombo Controls Constants

Appearance Constants

Constant | Value | Description
dblFlat | 0 | Flat appearance of DataList or DBCombo control.
dbl3D | 1 | Three-dimensional appearance of DataList or DBCombo control.

Area Constants (DBCombo Only)

Constant | Value | Description
dbcAreaButton | 0 | Returns the location of the DBCombo control's button when a Click or Double-Click event occurs there.
dbcAreaEdit | 1 | Returns the location of the DBCombo control's text box when a Click or Double-Click event occurs there.
dbcAreaList | 2 | Returns the location of the DBCombo control's list box when a Click or Double-Click event occurs there.

Match Entry Constants

Constant | Value | Description
dblBasicMatching | 0 | Basic matching
dblExtendedMatching | 1 | Extended matching

Mousepointer Constants

Constant | Value | Description
dblDefault | 0 | (Default) Shape determined by the object
dblArrow | 1 | Arrow
dblCross | 2 | Cross (cross-hair pointer)
dblIBeam | 3 | I-Beam
dblIcon | 4 | Icon (small square within a square)
dblSize | 5 | Size (four-pointed arrow pointing north, south, east, and west)
dblSizeNESW | 6 | Size NE SW (double arrow pointing northeast and southwest)
dblSizeNS | 7 | Size N S (double arrow pointing north and south)
dblSizeNWSE | 8 | Size NW SE (double arrow pointing northwest and southeast)
dblSizeEW | 9 | Size E W (double arrow pointing east and west)
dblUpArrow | 10 | Up Arrow
dblHourglass | 11 | Hourglass (wait)
dblNoDrop | 12 | No Drop
dblArrowHourglass | 13 | Arrow and hourglass
dblArrowQuestion | 14 | Arrow and question mark
dblSizeAll | 15 | Size all
dblCustom | 99 | Custom icon specified by the MouseIcon property

Style Constants

Constant | Value | Description
dbcDropdownCombo | 0 | Drop-down combo
dbcSimpleCombo | 1 | Simple combo
dbcDropdownList | 2 | Drop-down list

OLE Drag Constants

Constant | Value | Description
dblOLEDragManual | 0 | Manual dragging
dblOLEDragAutomatic | 1 | Automatic

OLE Drop Effect Constants

Constant | Value | Description
dblOLEDropEffectNone | 0 | Drop target cannot accept the data
dblOLEDropEffectCopy | 1 | Drop results in a copy; the original data is untouched by the drag source.
dblOLEDropEffectMove | 2 | Drag source should remove the data
dblOLEDropEffectScroll | -2147483648 | Scrolling is about to start or is currently occurring in the target; this value is used in addition to the other values

OLE Drop Constants

Constant | Value | Description
dblOLEDropNone | 0 | Don't allow drops
dblOLEDropManual | 1 | Manual

Drag Over Constants

Constant | Value | Description
dblEnter | 0 | OLE object is being dragged within the range of a target
dblLeave | 1 | OLE object is being dragged out of the range of a target
dblOver | 2 | OLE object has moved from one position in the target to another

Clipboard Constants

Constant | Value | Description
dblCFText | 1 | Text
dblCFBitmap | 2 | Bitmap (.bmp file)
dblCFMetafile | 3 | Metafile (.wmf file)
dblCFDIB | 8 | Device-independent bitmap (DIB)
dblCFPalette | 9 | Color palette
dblCFEMetafile | 14 | Enhanced Metafile (EMF files)
dblCFFiles | 15 | List of Files
dblCFRTF | -16639 | Rich Text Format (.rtf file)

Error Constants

Constant | Value | Description
dblDataNotSetForFormat | 676 | Requested data was not supplied to the DataObject during the OLESetData event.
dblDataObjectLocked | 672 | DataObject formats list may not be cleared or expanded outside of the OLEStartDrag event.
dblExpectedAnArgument | 673 | Expected at least one argument.
dblFormatNotByteArray | 675 | Non-intrinsic OLE drag and drop formats used with SetData require Byte array data. GetData may return more bytes than were given to SetData.
dblGetNotSupported | 394 | Property is write-only.
dblInvalidObjectUse | 425 | Invalid object use.
dblInvalidProcedureCall | 5 | Invalid procedure call.
dblInvalidPropertyValue | 380 | Invalid property value.
dblOutOfMemory | 7 | Out of memory.
dblRecursiveOleDrag | 674 | Illegal recursive invocation of OLE drag and drop.
dblSetNotPermitted | 387 | Property can't be set on this control.
dblWrongClipboardFormat | 461 | Specified format doesn't match format or date.


Click Event (DBCombo Control)

Occurs when the user presses and then releases a mouse button over the DBCombo control. This event also occurs by pressing the up or down arrow keys on the keyboard to select an item.

Syntax

Private Sub object_Click( [index As Integer ,] Area As Integer )

The Click event syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
index | An integer that uniquely identifies a control if it's in a control array.
Area | An integer expression that specifies where the control was clicked, as described below.

The Area parameter can contain the following values:

Constant | Value | Description
dbcAreaButton | 0 | The user clicked the button on the DBCombo control.
dbcAreaEdit | 1 | The user click in the text box part of the DBCombo control.
dbcAreaList | 2 | The user clicked in the drop-down list part of the DBCombo control.

Remarks

The DBCombo control does not have a DropDown event like the standard combo box to signal when the user drops down the list portion of the DBCombo control. Instead the user can use the Area parameter in the Click event to tell the user which area in the DBCombo control the user clicked.

Typically, you attach a Click event procedure to a control to carry out commands and command-like actions.

Clicking a control generates MouseDown and MouseUp events in addition to the Click event. When you're attaching event procedures for these related events, be sure that their actions don't conflict. If the order of events is important in your application, test the control to determine the event order.

Note To distinguish between the left, right, and middle mouse buttons, use the MouseDown and MouseUp events.


DblClick Event (DBCombo Control)

Occurs when the user double-clicks the DBCombo control with the mouse button.

Syntax

Private Sub object_DblClick ( [index As Integer,] Area As Integer)

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
index | An integer that uniquely identifies a control if it's in a control array.
Area | An integer expression that specifies where the control was double clicked, as described below.

The Area parameter can contain the following values:

Constant | Value | Description
dbcAreaButton | 0 | The user double-clicked the button on the DBCombo control.
dbcAreaEdit | 1 | The user double-clicked in the text box part of the DBCombo control.
dbcAreaList | 2 | The user double-clicked in the list part of the DBCombo control. (This only occurs when the Style property is set to 1)

Remarks

You can use a DblClick event procedure for an implied action or use it to carry out multiple steps with a single action.

If DblClick doesn't occur within the system's double-click time limit, the object recognizes another Click event. The double-click time limit may vary because the user can set the double-click speed in the Control Panel.

Note To distinguish between the left, right, and middle mouse buttons, use the MouseDown and MouseUp events.


AboutBox Method

Displays the About box for the control.

Syntax

object.AboutBox

The object placeholder represents an object expression that evaluates to an object in the Applies To list.

Remarks

This is the same as clicking About in the Properties window.


BoundText Property

Returns or sets the value of the field specified by the BoundColumn property.

Syntax

object.BoundText [= value]

The BoundText property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
value | A string expression that specifies a data value.

Remarks

After a user makes a selection with a DataList or DataCombo control, the BoundText property contains the field value of the BoundColumn property. When an item in the list is selected, the item becomes available to the Data control specified by the DataSource property. The selection also appears in the text box portion of the DataCombo control where it can be edited. If the user enters a value in the text box portion, the list portion attempts to position to a matching item. If a match is found, the BoundText property value is set, based on the field value of the BoundColumn property. If no match is found, the BoundText property is set to Null.

You can use the BoundText property value to create a query that can then be used to find specific records:

Dim strQ As String
StrQ = "Select * From Products Where SupplierID = " & DataList1.BoundText
' Use the new query with an ADO Data Control to return a new recordset.
Adodc1.RecordSource = strQ

Positioning the Data control, specified by the DataSource property, to a new record sets the BoundText property to the value specified by DataField. The DataList or DataCombo control then searches the records in the list to see if the BoundText value matches the value of the field in the BoundColumn property. If a match is found, the record is highlighted in the list or placed in the text box portion of the DataCombo control.

Data Type

String


Locked Property (DataCombo, DataList Controls)

Returns or sets a value indicating whether any data in the object can be modified.

Syntax

object.Locked [= boolean]

The Locked property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
boolean | Optional. A Boolean expression that indicates whether data can change, as described in Settings.

Settings

The settings for boolean are:

Setting | Description
False | (Default) The data can be changed.
True | The data cannot be changed.


RowMember Property

Returns or sets the data member to be used to display list text.

Syntax

object.RowMember [= string]

The RowMember property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
string | Optional. The name of a data member.

Remarks

The RowMember property is equivalent to the DataMember property, and is used to fully qualify which set of data to bind to. When a data source supplies more than one data member, you must specify which to use before setting the DataField property.


Style Property (DataCombo Control)

Returns or sets a value that specifies the behavior and/or appearance of the control.

Syntax

object.Style [= integer]

The Style property syntax has these parts:

Part | Description
object | An object expression that evaluates to an object in the Applies To list.
integer | Optional. A numeric expression that determines the style of the control, as shown in Settings.

Settings

The settings for integer are:

Constant | Value | Description
dbcDropdownCombo | 0 | (Default) Dropdown Combo. Includes a drop-down list and a text box. The user can select from the list or type in the text box.
dbcSimpleCombo | 1 | Simple Combo. Includes a text box and a list, which doesn't drop down. The user can select from the list or type in the text box. Increase the Height property to display more of the list.
dbcDropdownList | 2 | Dropdown List. This style allows selection only from the drop-down list.


VisibleCount, VisibleItems Properties Example

The following sample code uses the VisibleCount and VisibleItems properties to display the fields in all the visible records of a DataList control:

Private Sub Command1_Click()
Dim I As Integer, fld As Field, msg As Variant

For I = 0 To DataList1.VisibleCount - 1
  Data1.Recordset.Bookmark = DataList1.VisibleItems(I)
  msg = ""
  For Each fld In Data1.Recordset.Fields
    msg = msg & fld.Value & "-"
  Next
  MsgBox msg
Next I

End Sub